IDL_Number

The IDL_Number class contains static methods that are available for all IDL numbers. In addition, because IDL_Number is a subclass of IDL_Variable, all of the IDL_Variable methods are also available.

Superclasses

IDL_Variable

IDL_Number

Ceil: Compute the ceiling.
Floor: Compute the floor.
Imaginary: Return the imaginary value.
Mean: Compute the mean.
Median: Compute the median.
Max: Return the value of the largest element.
Min: Return the value of the smallest element.
Product: Compute the product.
Real: Return the real value.
Round: Round the value.
Signum: Compute the signum.
Total: Compute the total.

Additional Information

Thread Pool Keywords

Many of the methods for IDL_Number are written to make use of IDL's thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for more information.

IDL_Number::Ceil

The IDL_Number::Ceil method returns the closest integer greater than or equal to the variable.

Examples

Print the ceil of a number:

num = 5.1

PRINT, num.Ceil( )

IDL prints:

Syntax

Result = var.Ceil( )

Return Value

If the variable is of type integer, its Result has the same value and type. In all other cases, Result is a 32-bit long integer with the same structure as the variable.

Arguments

None.

Keywords

L64

If set, the result type is 64-bit integer regardless of the variable's type. This is useful for situations in which a floating point number contains a value too large for a 32-bit integer.

IDL_Number::Floor

The IDL_Number::Floor method returns the closest integer less than or equal to the variable.

Examples

Print the floor of a number:

num = 5.9

PRINT, num.Floor( )

IDL prints:

Syntax

Result = var.Floor( )

Return Value

If the variable is of type integer, its Result has the same value and type. In all other cases, Result is a 32-bit long integer with the same structure as the variable.

Arguments

None.

Keywords

L64

If set, the result type is 64-bit integer regardless of the variable's type. This is useful for situations in which a floating point number contains a value too largefor a 32-bit integer.

IDL_Number::Imaginary

The IDL_Number::Imaginary method returns the imaginary part of a complex-valued variable.

Examples

Print the imaginary parts of a value:

num = COMPLEX([1, 2, 3], [4, 5, 6])

PRINT, num.Imaginary( )

IDL prints:

4.00000 5.00000 6.00000

Syntax

Result = var.Imaginary( )

Return Value

If the variable is double-precision, the result will be double-precision, otherwise the result will be single-precision floating-point.

Arguments

None.

Keywords

None.

IDL_Number::Mean

The IDL_Number::Mean method computes the mean of the numeric vector.

Examples

Print the mean value of a 15-element vector:

num = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]

PRINT, num.Mean( )

IDL prints:

66.7333

Syntax

Result = var.Mean( [DIMENSION=value] [, /DOUBLE] [, /NAN] )

Return Value

The average value of the variable's elements.

Arguments

None.

Keywords

DIMENSION

Set this keyword to a scalar indicating the dimension across which to calculate the mean. If this keyword is not present or is zero, the mean is computed across all dimensions of the variable. If this keyword is present, the mean is only calculated across a single dimension. In this case the result is an array with one less dimension than the variable.

DOUBLE

If this keyword is set, computations are done in double precision arithmetic.

NAN

Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the variable. Elements with the value NaN or Infinity are treated as missing data.

IDL_Number::Median

The IDL_Number::Median method returns the median value of a numeric vector.

Examples

Print the median value of a 15-element vector:

num = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]

PRINT, num.Median( )

IDL prints:

67.0000

Syntax

Result = var.Median( [Width] [, DIMENSION=value] [, /DOUBLE] [, /EVEN] )

Return Value

The median value of the variable if one parameter is present, or applies a one- or two-dimensional median filter of the specified width to the variable and returns the result.

Arguments

Width

The size of the one- or two-dimensional neighborhood to be used for the median filter. The neighborhood has the same number of dimensions as the variable.

Keywords

DIMENSION

Set this keyword to the dimension over which to find the median values of the variable. If this keyword is not present or is zero, the median is found over the entire variable and is returned as a scalar value. If this keyword is present and nonzero, the result is a “slice” of the variable that contains the median value elements, and the return value will be an array of one dimension less than the variable.

For example, if the dimensions of the variable are N1, N2, N3, and DIMENSION = 2, the dimensions of the result are (N1, N3), and element (i, j) of the result contains the median value of the variable[i, *, j]. IDL ignores this keyword if the Width argument is present.

DOUBLE

Set this keyword to force the computation to be done using double-precision arithmetic and to return a double-precision result.

EVEN

If the variable contains an even number of points (i.e. there is no middle number), MEDIAN returns the average of the two middle numbers. The returned value may not be an element of the variable.

If the variable contains an odd number of points, MEDIAN returns the median value. The returned value will always be an element of the variable—even if the EVEN keyword is set—since an odd number of points will always have a single middle value.

IDL_Number::Max

The IDL_Number::Max method returns the value of the largest element of the variable.

Examples

Print the largest element of a given array:

num = FINDGEN(100)

PRINT, num.Max( )

IDL prints:

99.0000

Syntax

Result = var.Max( [Max_Subscript] [, /ABSOLUTE] [, DIMENSION=value] [, MIN=variable] [, /NAN] [, SUBSCRIPT_MIN=variable] )

Return Value

The largest array element value. The type of the result is the same as the type of the variable.

Arguments

Max_Subscript

A named variable that, if supplied, is converted to a long integer containing the one-dimensional subscript of the maximum element. Otherwise, the system variable !C is set to the one-dimensional subscript of the maximum element.

Keywords

ABSOLUTE

If this keyword is set, IDL used the absolute value of each element when determining the maximum values. This keyword has no effect for arrays of type byte or unsigned integer.

Note: If ABSOLUTE is set then the sign of each value is ignored when searching for the maximum. However, the return value retains the negative sign if the value was indeed negative.

Tip: For complex input, by default MAX only compares the real component of each value. Use the ABSOLUTE keyword to force MAX to compare the absolute value of each value, and to return the complex value corresponding to the maximum absolute value.

DIMENSION

Set this keyword to the dimension over which to find the maximum values of an array. If this keyword is not present or is zero, the maximum is found over the entire array and is returned as a scalar value. If this keyword is present and nonzero, the result is the “slice” of the input array that contains the maximum value element, and the return values for Result, Max_Subscript, MIN, and SUBSCRIPT_MIN will all be arrays of one dimension less than the input array. That is, if the dimensions of Array are N1, N2, N3, and DIMENSION=2, the dimensions of the result are (N1, N3), and element (i,j) of the result contains the maximum value of Array[i, *, j].

For example:

arr = FINDGEN(2,3,2)

PRINT, arr

IDL prints:

0.00000 1.00000

2.00000 3.00000

4.00000 5.00000

6.00000 7.00000

8.00000 9.00000

10.0000 11.0000

PRINT, MAX(arr, DIMENSION=2)

IDL prints:

4.00000 5.00000

10.0000 11.0000

PRINT, MAX(arr, DIMENSION=1)

IDL prints:

1.00000 3.00000 5.00000

7.00000 9.00000 11.0000

MIN

A named variable to receive the value of the minimum array element. If you need to find both the minimum and maximum array values, use this keyword to avoid scanning the array twice with separate calls to MAX and MIN.

NAN

Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the input data. Elements with the value NaN or Infinity are treated as missing data.

Note: If the MAX function is run on an array containing NaN values and the NAN keyword is not set, an invalid result will occur.

SUBSCRIPT_MIN

Set this keyword equal to a named variable that will contain the one-dimensional subscript of the minimum element, the value of which is available via the MIN keyword.

IDL_Number::Min

The IDL_Number::Min method returns the value of the smallest element of Array. The type of the result is the same as that of the variable.

Examples

Print the absolute value of a number:

num = FINDGEN(100)

PRINT, num.Min( )

IDL prints:

0.000000

Syntax

Result = var.Min( [Min_Subscript] [, /ABSOLUTE] [, DIMENSION=value] [, MAX=variable] [, /NAN] [, SUBSCRIPT_MAX=variable] )

Return Value

The smallest array element value.

Arguments

Min_Subscript

A named variable that, if supplied, is converted to a long integer containing the one-dimensional subscript of the minimum element. Otherwise, the system variable !C is set to the one-dimensional subscript of the minimum element.

Keywords

ABSOLUTE

If this keyword is set, IDL uses the absolute value of each element when determining the minimum values. This keyword has no effect for arrays of type byte or unsigned integer.

Note: If ABSOLUTE is set, IDL ignores the sign of each value when searching for the minimum. However, the return value retains the negative sign if the value was indeed negative.

Tip: For complex input, MIN by default only compares the real component of each value. Use the ABSOLUTE keyword to force MIN to compare the absolute value of each value, and to return the complex value corresponding to the minimum absolute value.

DIMENSION

Set this keyword to the dimension over which to find the minimum values of an array. If this keyword is not present or is zero, the minimum is found over the entire array and is returned as a scalar value. If this keyword is present and nonzero, the result is the “slice” of the input array that contains the minimum value element, and the return values for Result, Min_Subscript, MAX, and SUBSCRIPT_MAX will all be arrays of one dimension less than the input array. That is, if the dimensions of Array are N1, N2, N3, and DIMENSION=2, the dimensions of the result are (N1, N3), and element (i,j) of the result contains the minimum value of Array[i, *, j].

For example:

arr = FINDGEN(2,3,2)

PRINT, arr

IDL prints:

0.00000 1.00000

2.00000 3.00000

4.00000 5.00000

6.00000 7.00000

8.00000 9.00000

10.0000 11.0000

PRINT, MIN(arr, DIMENSION=2)

IDL prints:

0.00000 1.00000

6.00000 7.00000

PRINT, MIN(arr, DIMENSION=1)

IDL prints:

0.00000 2.00000 4.00000

6.00000 8.00000 10.0000

MAX

The name of a variable to receive the value of the maximum array element. If you need to find both the minimum and maximum array values, use this keyword to avoid scanning the array twice with separate calls to MAX and MIN.

NAN

Note: If the MIN function is run on an array containing NaN values and the NAN keyword is not set, an invalid result will occur.

SUBSCRIPT_MAX

Set this keyword to a named variable that will contain the one-dimensional subscript of the maximum element, the value of which is available via the MAX keyword.

IDL_Number::Product

The IDL_Number::Product method returns the product of the elements within the variable.

Examples

Print the product of a numeric array:

num = [20, 10, 5, 5, 3]

PRINT, num.Product( )

IDL prints:

15000.000

Syntax

Result = var.Product( [Dimension] [, /CUMULATIVE] [, /INTEGER] [, /NAN] [, /PRESERVE_TYPE] )

Return Value

The product of the elements within the variable.

Arguments

Dimension

An optional argument specifying the dimension over which to compute the product, starting at one. If this argument is not present or zero, the product of all the array elements is returned. If this argument is present, the result is an array with one less dimension than Array.

For example, if the dimensions of Array are N₁, N₂, N₃, and Dimension is 2, the dimensions of the result are (N₁, N₃), and element [i, j] of the result contains the product:

Keywords

CUMULATIVE

If this keyword is set, the result is an array of the same size as the variable, with each element, i, containing the product of the variable elements 0 to i. This keyword also works with the Dimension parameter, in which case the cumulative product is performed over the given dimension. Note that if the variable has only a single element, then a scalar is returned.

Tip: If the variable is a temporary variable or an expression, and the result type matches the variable's type (for example by using the PRESERVE_TYPE keyword), then PRODUCT will perform the cumulative product in place and no additional memory will be used.

INTEGER

Set this keyword to perform the PRODUCT using integer arithmetic and to return an integer result. If the variable is of type ULONG64, then unsigned 64-bit integers are used for the computation and the Result is of type ULONG64. Otherwise, IDL uses signed 64-bit integers and the Result is of type LONG64. If the variable is complex and INTEGER is set, then only the real part of each value is used for the computation.

Note: If the variable has a large number of values or the values themselves are large, then the PRODUCT with the INTEGER keyword may easily overflow the largest 64-bit integer and return an incorrect result. In this case you may want to avoid using the INTEGER keyword.

NAN

Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the data. Elements with the value NaN or Infinity are treated as missing data with the value 1.

PRESERVE_TYPE

Set this keyword to perform the PRODUCT using the variable's type, and to return a result of the same type. The INTEGER keyword is ignored if PRESERVE_TYPE is set.

Note: For byte or integer data the PRODUCT with PRESERVE_TYPE may easily overflow the largest value for that type. In these cases you may want to use the INTEGER keyword instead.

IDL_Number::Real

The IDL_Number::Real method returns the real part of the complex-valued number.

Examples

Print the real parts of a value:

num = COMPLEX([1, 2, 3], [4, 5, 6])

PRINT, num.Real( )

IDL prints:

1.00000 2.00000 3.00000

Syntax

Result = var.Real( )

Return Value

If the variable is double-precision, the result will be double-precision, otherwise the result will be single-precision floating-point.

Arguments

None.

Keywords

None.

IDL_Number::Round

The IDL_Number::Round method rounds the number to its closest integer.

Examples

Print the rounded value of a number:

num = [5.1, 5.9]

PRINT, num.Round( )

IDL prints:

5 6

Syntax

Result = var.Round( )

Return Value

The integer closest to the number. If the variable is of type integer, its Result has the same value and type, otherwise, Result is returned as a 32-bit long integer with the same structure as the number.

Arguments

None.

Keywords

L64

If set, the result type is 64-bit integer no matter what is the type of the variable. This is useful for situations in which a floating point number contains a value too large to be represented in a 32-bit integer.

IDL_Number::Signum

The IDL_Number::Signum method returns the sign of each element of an array.

Examples

Print the signum value of a number:

num = -24601

PRINT, num.Signum( )

IDL prints:

-1

Syntax

Result = var.Signum( )

Return Value

A scalar or array of the same type and dimensions as the variable. If the variable is of type string, then the values are converted to single-precision floating point before computing the sign.

Arguments

None.

Keywords

None.

IDL_Number::Total

The IDL_Number::Total method returns the sum total of the values within the variable.

Examples

Print the total value of an array:

num = LINDGEN(100, 100)

PRINT, num.Total( )

IDL prints:

49995000

Syntax

Result = var.Total( [Dimension] [, /CUMULATIVE] [, /DOUBLE] [, /INTEGER] [, /NAN] [, /PRESERVE_TYPE] )

Return Value

The sum total of the values within the variable.

Arguments

Dimension

An optional argument specifying the dimension over which to compute the total, starting at one. If this argument is not present or zero, the total of all the array elements is returned. If this argument is present, the result is an array with one less dimension than the input variable.

For example, if the dimensions of the input variable are N₁, N₂, N₃, and Dimension is set to 2, the dimensions of the result are (N₁, N₃), and element [i, j] of the result contains the sum:

Keywords

CUMULATIVE

If this keyword is set, the result is an array of the same size as the input, with each element, i, containing the sum of the input array elements 0 to i. This keyword also works with the Dimension parameter, in which case the sum is performed over the given dimension. Note that if the input only has a single element, then a scalar is returned.

DOUBLE

Set this keyword to force the summation to be done using double-precision arithmetic. By default, if the input is of type DOUBLE, DCOMPLEX, LONG64, or ULONG64, IDL does the summation using double precision; otherwise IDL does the summation using single precision. If this keyword is set to zero, IDL still does the summation using the default precision, but the result is converted to single precision before returning.

INTEGER

Set this keyword to perform the TOTAL using integer arithmetic, and to return an integer result. If the input variable is of type ULONG64 then unsigned 64-bit integers are used for the computation and the Result is of type ULONG64, otherwise signed 64-bit integers are used and the Result is of type LONG64. If the input variable is complex and INTEGER is set, then only the real part of each value is used for the computation. The DOUBLE keyword is ignored if INTEGER is set.

Note: If var has a large number of values or the values themselves are large, then the TOTAL with the INTEGER keyword may easily overflow the largest 64-bit integer and return an incorrect result. In this case you may want to avoid using the INTEGER keyword.

NAN

Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the input data. Elements with the value NaN or Infinity are treated as missing data.

Note: Since the value NaN is treated as missing data, if var contains only NaN values the TOTAL routine will return 0.

PRESERVE_TYPE

Set this keyword to perform the TOTAL using the input type, and to return a result of the same type. The DOUBLE and INTEGER keywords are ignored if PRESERVE_TYPE is set.

Note: For byte or integer data the TOTAL with PRESERVE_TYPE may easily overflow the largest value for that type. The PRESERVE_TYPE keyword is only useful if you know that your values will not overflow, or you want to exploit the overflow, for example in computing a checksum. Otherwise, you may want to use the INTEGER keyword instead.

Version History

8.4	Introduced